package com.linkgie.galaxyframework.kvstorage;

public interface PrimitiveKVMap {
	

	/**
	 * 指定的键是否存在；
	 * 
	 * @param key
	 * @return
	 */
	boolean contains(String key);

	/**
	 * 指定的键是否存在；
	 * 
	 * @param key
	 * @return
	 */
	boolean contains(byte[] key);


	/**
	 * 以基本类型 boolean 返回指定 key 的值；
	 * 
	 * <p>
	 * 如果值为空，则抛出 {@link NullValueException} 异常；<br>
	 * 如果类型转换失败，则抛出 {@link DataCodecException} 异常；
	 * 
	 * @param key
	 * @return
	 */
	boolean getBooleanValue(String key);
	
	/**
	 * 以包装类型 boolean 返回指定 key 的值；
	 * 
	 * <p>
	 * 如果值不存在，则返回 null ；<br>
	 * 如果类型转换失败，则抛出 {@link DataCodecException} 异常；
	 * 
	 * @param key
	 * @return
	 */
	Boolean getBoolean(String key);

	void setBoolean(String key, boolean value);

	void setBoolean(byte[] key, boolean value);

	boolean insertBoolean(String key, boolean value);

	boolean insertBoolean(byte[] key, boolean value);

	boolean updateBoolean(String key, boolean value);

	boolean updateBoolean(byte[] key, boolean value);

	/**
	 * 以基本类型 short 返回指定 key 的值；
	 * 
	 * <p>
	 * 如果值为空，则抛出 {@link NullValueException} 异常；<br>
	 * 如果类型转换失败，则抛出 {@link DataCodecException} 异常；
	 * 
	 * @param key
	 * @return
	 */
	short getShortValue(String key);
	
	/**
	 * 以包装类型 short 返回指定 key 的值；
	 * 
	 * <p>
	 * 如果值不存在，则返回 null ；<br>
	 * 如果类型转换失败，则抛出 {@link DataCodecException} 异常；
	 * 
	 * @param key
	 * @return
	 */
	Short getShort(String key);

	void setShort(String key, short value);

	void setShort(byte[] key, short value);

	boolean insertShort(String key, short value);

	boolean insertShort(byte[] key, short value);

	boolean updateShort(String key, short value);

	boolean updateShort(byte[] key, short value);

	/**
	 * 以基本类型 char 返回指定 key 的值；
	 * 
	 * <p>
	 * 如果值为空，则抛出 {@link NullValueException} 异常；<br>
	 * 如果类型转换失败，则抛出 {@link DataCodecException} 异常；
	 * 
	 * @param key
	 * @return 
	 */
	char getCharValue(String key);
	
	/**
	 * 以包装类型 char 返回指定 key 的值；
	 * 
	 * <p>
	 * 如果值不存在，则返回 null ；<br>
	 * 如果类型转换失败，则抛出 {@link DataCodecException} 异常；
	 * 
	 * @param key
	 * @return 
	 */
	Character getChar(String key);

	void setChar(String key, char value);

	void setChar(byte[] key, char value);

	boolean insertChar(String key, char value);

	boolean insertChar(byte[] key, char value);

	boolean updateChar(String key, char value);

	boolean updateChar(byte[] key, char value);

	/**
	 * 以基本类型 int 返回指定 key 的值；
	 * 
	 * <p>
	 * 如果值为空，则抛出 {@link NullValueException} 异常；<br>
	 * 如果类型转换失败，则抛出 {@link DataCodecException} 异常；
	 * 
	 * @param key
	 * @return
	 */
	int getIntValue(String key);
	
	/**
	 * 以包装类型 int 返回指定 key 的值；
	 * 
	 * <p>
	 * 如果值不存在，则返回 null ；<br>
	 * 如果类型转换失败，则抛出 {@link DataCodecException} 异常；
	 * 
	 * @param key
	 * @return
	 */
	Integer getInt(String key);

	void setInt(String key, int value);

	void setInt(byte[] key, int value);

	boolean insertInt(String key, int value);

	boolean insertInt(byte[] key, int value);

	boolean updateInt(String key, int value);

	boolean updateInt(byte[] key, int value);

	/**
	 * 以基本类型 long 返回指定 key 的值；
	 * 
	 * <p>
	 * 如果值为空，则抛出 {@link NullValueException} 异常；<br>
	 * 如果类型转换失败，则抛出 {@link DataCodecException} 异常；
	 * 
	 * @param key
	 * @return
	 */
	long getLongValue(String key);
	
	Long getLong(String key);

	void setLong(String key, long value);

	void setLong(byte[] key, long value);

	boolean insertLong(String key, long value);

	boolean insertLong(byte[] key, long value);

	boolean updateLong(String key, long value);

	boolean updateLong(byte[] key, long value);

	/**
	 * 以基本类型 float 返回指定 key 的值；
	 * 
	 * <p>
	 * 如果值为空，则抛出 {@link NullValueException} 异常；<br>
	 * 如果类型转换失败，则抛出 {@link DataCodecException} 异常；
	 * 
	 * @param key
	 * @return
	 */
	float getFloatValue(String key);
	
	/**
	 * 以包装类型 float 返回指定 key 的值；
	 * 
	 * <p>
	 * 如果值不存在，则返回 null ；<br>
	 * 如果类型转换失败，则抛出 {@link DataCodecException} 异常；
	 * 
	 * @param key
	 * @return
	 */
	Float getFloat(String key);

	void setFloat(String key, float value);

	void setFloat(byte[] key, float value);

	boolean insertFloat(String key, float value);

	boolean insertFloat(byte[] key, float value);

	boolean updateFloat(String key, float value);

	boolean updateFloat(byte[] key, float value);

	/**
	 * 以基本类型 double 返回指定 key 的值；
	 * 
	 * <p>
	 * 如果值为空，则抛出 {@link NullValueException} 异常；<br>
	 * 如果类型转换失败，则抛出 {@link DataCodecException} 异常；
	 * 
	 * @param key
	 * @return
	 */
	double getDoubleValue(String key);
	
	/**
	 * 以包装类型 double 返回指定 key 的值；
	 * 
	 * <p>
	 * 如果值不存在，则返回 null ；<br>
	 * 如果类型转换失败，则抛出 {@link DataCodecException} 异常；
	 * 
	 * @param key
	 * @return
	 */
	Double getDouble(String key);

	void setDouble(String key, double value);

	void setDouble(byte[] key, double value);

	boolean insertDouble(String key, double value);

	boolean insertDouble(byte[] key, double value);

	boolean updateDouble(String key, double value);

	boolean updateDouble(byte[] key, double value);

	/**
	 * 删除；
	 * 
	 * @param key
	 */
	void delete(String key);

	/**
	 * 删除；
	 * 
	 * @param key
	 */
	void delete(byte[] key);

	/**
	 * 检索当前存储空间中包含指定前缀的所有键 ；
	 * <p>
	 * 检索的方式为升序检索；
	 * 
	 * @param keyPrefix 要检索的前缀；如果为 null 或者空字符，则返回当前存储的键空间下的全部键；
	 * @return
	 */
	PrimitiveKeyIterator<String> seekInPrefix(String keyPrefix);

	/**
	 * 检索当前存储空间中包含指定前缀的所有键 ；
	 * <p>
	 * 检索的方式为升序检索；
	 * 
	 * @param keyPrefix 要检索的前缀；如果为 null 或者空字符，则返回当前存储的键空间下的全部键；
	 * @return
	 */
	PrimitiveKeyIterator<byte[]> seekInPrefix(byte[] keyPrefix);

	/**
	 * 升序检索当前存储空间中从指定的“起点”（包含）开始的所有键；
	 * <p>
	 * 
	 * @param startpoint 起点，可以是键或键的前缀；如果为空，则从存储空间的首个键开始检索；
	 * @return 大于等于“起点”的所有键；
	 */
	default PrimitiveKeyIterator<String> seek(String startpoint) {
		return seek(startpoint, null);
	}

	/**
	 * 升序检索当前存储空间中从指定的“起点”（包含）开始的所有键；
	 * <p>
	 * 
	 * @param startpoint 起点，可以是键或键的前缀；如果为空，则从存储空间的首个键开始检索；
	 * @return 大于等于“起点”的所有键；
	 */
	default PrimitiveKeyIterator<byte[]> seek(byte[] startpoint) {
		return seek(startpoint, null);
	}

	/**
	 * 升序检索当前存储空间中从指定的“起点”（包含）到“终点”（包含）的所有键；
	 * <p>
	 * 
	 * 调用者需要保证起“起点”小于“终点”（按自然顺序），否则返回的迭代器将不包含任何键；
	 * 
	 * @param startpoint 起点，可以是键或键的前缀；不包含在返回结果中；如果为空，则从首个键开始检索；
	 * @param endpoint   终点，可以是键或键的前缀；不包含在返回结果中；如果为空，则从起点开始检索余下的全部键；
	 * @return 大于等于“起点”且小于等于“终点”的所有键；
	 */
	default PrimitiveKeyIterator<String> seek(String startpoint, String endpoint) {
		return seek(startpoint, true, endpoint, true);
	}

	/**
	 *  升序检索当前存储空间中从指定的“起点”（包含）到“终点”（包含）的所有键；
	 * <p>
	 * 
	 * 调用者需要保证起“起点”小于“终点”（按自然顺序），否则返回的迭代器将不包含任何键；
	 * 
	 * @param startpoint 起点，可以是键或键的前缀；不包含在返回结果中；如果为空，则从首个键开始检索；
	 * @param endpoint   终点，可以是键或键的前缀；不包含在返回结果中；如果为空，则从起点开始检索余下的全部键；
	 * @return 大于等于“起点”且小于等于“终点”的所有键；
	 */
	default PrimitiveKeyIterator<byte[]> seek(byte[] startpoint, byte[] endpoint) {
		return seek(startpoint, true, endpoint, true);
	}

	/**
	 * 升序检索当前存储空间中从指定的“起点”到“终点”的所有键；
	 * <p>
	 * 
	 * 调用者需要保证起“起点”小于“终点”（按自然顺序），否则返回的迭代器将不包含任何键；
	 * 
	 * @param startpoint    起点，可以是键或键的前缀；如果为空，则从首个键开始检索；
	 * @param excludedStart 是否排除起点；
	 * @param endpoint      终点，可以是键或键的前缀；如果为空，则从起点开始检索余下的全部键；
	 * @param excludedEnd   是否排除
	 * @return “起点”和“终点”之间的所有键；
	 */
	PrimitiveKeyIterator<String> seek(String startpoint, boolean excludedStart, String endpoint, boolean excludedEnd);

	/**
	 * 升序检索当前存储空间中从指定的“起点”到“终点”的所有键；
	 * <p>
	 * 
	 * 调用者需要保证起“起点”小于“终点”（按自然顺序），否则返回的迭代器将不包含任何键；
	 * 
	 * @param startpoint    起点，可以是键或键的前缀；如果为空，则从首个键开始检索；
	 * @param excludedStart 是否排除起点；
	 * @param endpoint      终点，可以是键或键的前缀；如果为空，则从起点开始检索余下的全部键；
	 * @param excludedEnd   是否排除
	 * @return “起点”和“终点”之间的所有键；
	 */
	PrimitiveKeyIterator<byte[]> seek(byte[] startpoint, boolean excludedStart, byte[] endpoint, boolean excludedEnd);

	/**
	 * 降序检索当前存储空间中从指定的“起点”（包含）开始的所有键；
	 * <p>
	 * 
	 * @param startpoint 起点，可以是键或键的前缀；如果为空，则从存储空间的最后一个键开始检索；
	 * @return 小于等于“起点”的所有键；
	 */
	default PrimitiveKeyIterator<String> seekDesc(String startpoint) {
		return seekDesc(startpoint, null);
	}

	/**
	 * 降序检索当前存储空间中从指定的“起点”（包含）开始的所有键；
	 * <p>
	 * 
	 * 检索的方式为降序检索，从“起点”到键空间下的第一个键；
	 * 
	 * @param startpoint 起点，可以是键或键的前缀；如果为空，则从存储空间的最大的键开始检索；
	 * @return 小于等于“起点”的所有键；
	 */
	default PrimitiveKeyIterator<byte[]> seekDesc(byte[] startpoint) {
		return seekDesc(startpoint, null);
	}

	/**
	 * 降序检索当前存储空间中从指定的“起点”（包含）到“终点”（包含）的所有键；
	 * <p>
	 * 
	 * 调用者需要保证起“起点”大于“终点”（按自然顺序），否则返回的迭代器将不包含任何键；
	 * 
	 * @param startpoint 起点，可以是键或键的前缀；不包含在返回结果中；如果为空，则从最后一个键开始检索；
	 * @param endpoint   终点，可以是键或键的前缀；不包含在返回结果中；如果为空，则从起点开始检索余下的全部键；
	 * @return 小于等于“起点”且大于等于“终点”的所有键；
	 */
	default PrimitiveKeyIterator<String> seekDesc(String startpoint, String endpoint) {
		return seekDesc(startpoint, true, endpoint, true);
	}

	/**
	 * 升序检索当前存储空间中从指定的“起点”（包含）到“终点”（包含）的所有键；
	 * <p>
	 * 
	 * 调用者需要保证起“起点”大于“终点”（按自然顺序），否则返回的迭代器将不包含任何键；
	 * 
	 * @param startpoint 起点，可以是键或键的前缀；不包含在返回结果中；如果为空，则从最后一个键开始检索；
	 * @param endpoint   终点，可以是键或键的前缀；不包含在返回结果中；如果为空，则从起点开始检索余下的全部键；
	 * @return 小于等于“起点”且大于等于“终点”的所有键；
	 */
	default PrimitiveKeyIterator<byte[]> seekDesc(byte[] startpoint, byte[] endpoint) {
		return seekDesc(startpoint, true, endpoint, true);
	}

	/**
	 * 降序检索当前存储空间中从指定的“起点”到“终点”的所有键；
	 * <p>
	 * 
	 * 调用者需要保证起“起点”大于“终点”（按自然顺序），否则返回的迭代器将不包含任何结果；
	 * 
	 * @param startpoint    起点，可以是键或键的前缀；如果为空，则从最后一个键开始检索；
	 * @param excludedStart 是否排除起点；
	 * @param endpoint      终点，可以是键或键的前缀；如果为空，则从起点开始检索余下的全部键；
	 * @param excludedEnd   是否排除
	 * @return “起点”和“终点”之间的所有键；
	 */
	PrimitiveKeyIterator<String> seekDesc(String startpoint, boolean excludedStart, String endpoint,
			boolean excludedEnd);

	/**
	 * 降序检索当前存储空间中从指定的“起点”到“终点”的所有键；
	 * <p>
	 * 
	 * 调用者需要保证起“起点”大于“终点”（按自然顺序），否则返回的迭代器将不包含任何结果；
	 * 
	 * @param startpoint    起点，可以是键或键的前缀；如果为空，则从最后一个键开始检索；
	 * @param excludedStart 是否排除起点；
	 * @param endpoint      终点，可以是键或键的前缀；如果为空，则从起点开始检索余下的全部键；
	 * @param excludedEnd   是否排除终点；
	 * @return “起点”和“终点”之间的所有键；
	 */
	PrimitiveKeyIterator<byte[]> seekDesc(byte[] startpoint, boolean excludedStart, byte[] endpoint,
			boolean excludedEnd);

}